Summary

Closes #14263.

filterwarnings = error::ResourceWarning does not fail tests that leak resources through a reference cycle. collect_unraisable wraps the captured warning in PytestUnraisableExceptionWarning, a class the user has not filtered.

collect_unraisable now checks warnings.filters before wrapping. When an active error filter targets a class that the captured warning is an instance of, collect_unraisable re-raises that warning directly; the resulting exception fails the test.

Visual

Behavior on main: this test passes despite user configuring for ResourceWarning to trigger an error. Pictured test_leak.py triggers ResourceWarning.

After PR: raises error as expected

Scope

collect_unraisable chooses between two branches when it processes a queued unraisable:

• Unwrap (new in this PR): re-raise the unraisable's inner warning class directly, so the user's error::<class> filter fails the test as written. Applies only when an active error::<class> filter matches that class.
• Wrap (pre-PR behavior, still the default): wrap the unraisable in PytestUnraisableExceptionWarning and emit it via warnings.warn. A __del__ that raises a Warning without a matching error::<class> filter still hits this branch.

Suites without error::<warning> filters see no change.

The unwrap-branch filter check is action == "error" plus issubclass(warning_class, filter_category). It does not re-run Python's warnings module's full match logic, which additionally tests the filter's message_regex, module_regex, and lineno fields. Consequence: for users with narrowly-scoped filters like error:some_msg:ResourceWarning::42, this branch can fail a test on a ResourceWarning whose message wouldn't have matched the regex. For broad filters like error::ResourceWarning the behavior matches user intent.

Branch structure

Three red→green commit pairs plus a comment-cleanup commit. Each red commit fails the named test; the next commit makes it pass.

1. 92c7681a2 (red) → 4cf46d4f9 (fix): test_refcycle_resource_warning_filter exercises the user-visible wrap-vs-unwrap behavior covered in Summary.
2. 21d334ad1 (red) → 839a20a0c (fix): the move-GC hardening from Fix session-end gc in unraisableexception plugin to respect warning filters #14273. test_unraisable_decouples_from_cleanup_stack_order uses @hookimpl(trylast=True) to force a LIFO cleanup-stack order that PR apply warnings filter as soon as possible, and remove it as late as possible #13057 incidentally avoided. The fix moves gc.collect() and queue processing into pytest_unconfigure, which runs before _cleanup_stack.close().
3. dead24a90 (red) → ef0d16180 (fix): test_pytest_unconfigure_survives_failed_pytest_configure raises UsageError from a conftest's pytest_configure, which exposed a KeyError after step 2 moved the GC call out of config.add_cleanup. The fix adds a stash-presence check at the top of pytest_unconfigure.

Cleanup: 56f71b785 tightens the new comments in unraisableexception.py.

Testing

For a one-file check, save this as test_leak.py:

import gc; gc.disable()  # let the cycle survive to session-end gc

def test_it():
    f = open(__file__)
    cycle = [f]
    cycle.append(cycle)

Then run pytest -W error::ResourceWarning test_leak.py. The -W flag drives the same code path as the pytest.ini filterwarnings setting. On main the test passes (bug); on this branch it exits 1 with the inner ResourceWarning raised directly, no PytestUnraisableExceptionWarning wrapper.

If you run from inside the pytest source tree, the repo's pyproject.toml [tool.pytest] filterwarnings = ['error', ...] promotes every warning to an error. Comment out the bare 'error' entry, or run the snippet from outside the repo.

• Regression tests
• Manually verify bug on main
  • Check out main, install (pip install -e .), run the adapted reproducer. Scenario 1 exits 0 (bug confirmed). Scenario 2 exits 1.
• Manually verify branch fix. Check out branch, run the same reproducer. Scenario 1 now exits 1 with the inner ResourceWarning raised. Scenario 2 still exits 1.
• Check out any of the red commits (92c7681a2, 21d334ad1, dead24a90); the named test fails. Check out the next commit; it passes.

External suite tests

(time-permitting; I don't think this needs to block review)

• Verify the scope guard. Run a suite that raises a Warning from __del__ without a matching error filter against this branch.
• Run a real project that uses error::DeprecationWarning or error::UserWarning filters against this branch. Nothing previously-passing should now fail.

AI disclosure

• Yes. Used AI assist with code writing and learning artifacts.
• Knowledge gaps on my side: new to repo. Spent a good amount of time researching how Python reclaims memory, sys.unraisable hook, and manually running the regression test before and after changes.
• References used
  • https://adamj.eu/tech/2025/01/02/python-unraisiable-exceptions/
  • https://adamj.eu/tech/2025/01/07/python-test-unraisable-exceptions/
  • https://www.youtube.com/watch?v=G4Lya0KVG1E
  • https://vstinner.github.io/sys-unraisablehook-python38.html
  • https://docs.python.org/3.11/library/sys.html#sys.unraisablehook

Side note: open to feedback to pull some of the PR comments into the code if helpful

Changelog

changelog/14263.bugfix.rst.